@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/foundations/color.md

@@ -0,0 +1,522 @@
+# Color
+
+Color tokens for text, surfaces, borders, and status, with contrast rules.
+
+## Overview
+
+Color in Tempo is mostly black and white. Text, fills, and edges are neutrals at different strengths, so a screen reads through contrast and hierarchy rather than hue. A white card on a light gray page, black text, and one black primary action carry most of the interface.
+
+Hue is the exception. Green, orange, and red report status in alerts, banners, and field states, and never decorate. Blue and violet mark tips and announcements.
+
+Every color is a token named for its role. Backgrounds and containers fill, content colors text and icons, and lines and borders draw edges. Each token holds a light and a dark value, so one token works in both schemes.
+
+## Scales
+
+Scales hold the raw colors that tokens draw from. Use a scale step directly only for charts and categories.
+
+### Neutral
+
+| TokenLogo | Value |
+| --- | --- |
+| `neutral.000` | `#fff` |
+| `neutral.003` | `#f7f7f7` |
+| `neutral.004` | `#f5f5f5` |
+| `neutral.006` | `#f0f0f0` |
+| `neutral.008` | `#ebebeb` |
+| `neutral.012` | `#e0e0e0` |
+| `neutral.016` | `#d6d6d6` |
+| `neutral.020` | `#ccc` |
+| `neutral.024` | `#c2c2c2` |
+| `neutral.028` | `#b8b8b8` |
+| `neutral.032` | `#adadad` |
+| `neutral.036` | `#a3a3a3` |
+| `neutral.040` | `#999` |
+| `neutral.044` | `#8f8f8f` |
+| `neutral.048` | `#858585` |
+| `neutral.052` | `#7a7a7a` |
+| `neutral.056` | `#707070` |
+| `neutral.060` | `#666` |
+| `neutral.064` | `#5c5c5c` |
+| `neutral.068` | `#525252` |
+| `neutral.072` | `#474747` |
+| `neutral.076` | `#3d3d3d` |
+| `neutral.080` | `#333` |
+| `neutral.084` | `#292929` |
+| `neutral.088` | `#1f1f1f` |
+| `neutral.092` | `#141414` |
+| `neutral.096` | `#0a0a0a` |
+| `neutral.100` | `#000` |
+
+Each step names a percentage of black, from white to black.
+
+### Shade and Tint
+
+| TokenLogo | Value |
+| --- | --- |
+| `neutral.shade.000` | `#00000000` |
+| `neutral.shade.003` | `#00000008` |
+| `neutral.shade.004` | `#0000000a` |
+| `neutral.shade.008` | `#00000014` |
+| `neutral.shade.012` | `#0000001f` |
+| `neutral.shade.016` | `#00000029` |
+| `neutral.shade.020` | `#00000033` |
+| `neutral.shade.032` | `#00000052` |
+| `neutral.shade.040` | `#00000066` |
+| `neutral.shade.056` | `#0000008f` |
+| `neutral.shade.060` | `#00000099` |
+| `neutral.shade.080` | `#000000cc` |
+
+| TokenLogo | Value |
+| --- | --- |
+| `neutral.tint.000` | `#ffffff00` |
+| `neutral.tint.008` | `#ffffff14` |
+| `neutral.tint.012` | `#ffffff1f` |
+| `neutral.tint.016` | `#ffffff29` |
+| `neutral.tint.020` | `#ffffff33` |
+| `neutral.tint.024` | `#ffffff3d` |
+| `neutral.tint.040` | `#ffffff66` |
+| `neutral.tint.048` | `#ffffff7a` |
+| `neutral.tint.052` | `#ffffff85` |
+| `neutral.tint.056` | `#ffffff8f` |
+| `neutral.tint.064` | `#ffffffa3` |
+| `neutral.tint.080` | `#ffffffcc` |
+
+Shades are black and tints are white, at the opacity the step names, so a fill keeps the same relative step on any background.
+
+### Accent
+
+| Hue | Background | Foreground |
+| --- | --- | --- |
+| blue | `accent.blue.background` (`#4471ed` light, `#7498fb` dark) | `accent.blue.foreground` (`#3059d3` light, `#7498fb` dark) |
+| cyan | `accent.cyan.background` (`#00aacb` light, `#48cce6` dark) | `accent.cyan.foreground` (`#056e85` light, `#48cce6` dark) |
+| green | `accent.green.background` (`#13a963` light, `#59e5a4` dark) | `accent.green.foreground` (`#007441` light, `#59e5a4` dark) |
+| magenta | `accent.magenta.background` (`#cc055b` light, `#e54088` dark) | `accent.magenta.foreground` (`#ba0352` light, `#e54088` dark) |
+| olive | `accent.olive.background` (`#95b226` light, `#c4dc65` dark) | `accent.olive.foreground` (`#596d01` light, `#c4dc65` dark) |
+| orange | `accent.orange.background` (`#e06f12` light, `#fa8e36` dark) | `accent.orange.foreground` (`#a14d04` light, `#fa8e36` dark) |
+| purple | `accent.purple.background` (`#ba59dd` light, `#cf79ef` dark) | `accent.purple.foreground` (`#9835ba` light, `#cf79ef` dark) |
+| red | `accent.red.background` (`#eb3417` light, `#f55c45` dark) | `accent.red.foreground` (`#bf1d00` light, `#f55c45` dark) |
+| violet | `accent.violet.background` (`#7e59e4` light, `#9877f1` dark) | `accent.violet.foreground` (`#6f47d1` light, `#9877f1` dark) |
+
+Each hue has a background, which switches with the scheme, and a foreground for accent text that stays readable on every surface.
+
+## Backgrounds
+
+Two backgrounds sit below every component, and a third fills small chips on a visual. Components on them take their fills, borders, and text from the tokens that follow.
+
+* `background.primary` (`#f5f5f5` light, `#141414` dark): The page behind cards, tables, and the app shell.
+* `background.elevated` (`#fff` light, `#1a1a1a` dark): Cards, dialogs, menus, and popovers above the page.
+* `background.secondary` (`#fff` light, `#141414` dark): Badges and chips that sit on a visual or a tint.
+
+## Containers
+
+Containers fill components such as menu items, badges, and selected rows. They are translucent, so a fill keeps the same relative step on the page and on an elevated surface.
+
+* `container.subtle` (`#00000008` light, `#ffffff14` dark): The faintest fill, such as a disabled field.
+* `container.regular` (`#0000000a` light, `#ffffff14` dark): Secondary buttons, filled fields, and tags.
+* `container.strong` (`#00000014` light, `#ffffff29` dark): Hovered and pressed controls, and slider tracks.
+* `container.positive` (`rgb(19 169 99 / 0.08)` light, `rgb(89 229 164 / 0.16)` dark): Positive alerts and tags, and copied values.
+* `container.warning` (`rgb(224 111 18 / 0.08)` light, `rgb(250 142 54 / 0.16)` dark): Warning alerts, banners, and tags.
+* `container.negative` (`rgb(235 52 23 / 0.08)` light, `rgb(245 92 69 / 0.16)` dark): Negative alerts, banners, and tags.
+
+## Borders
+
+Lines outline edges and divide content, and borders mark focus and validation.
+
+* `line.secondary` (`#00000014` light, `#ffffff14` dark): Dividers, table borders, and resting outlined fields.
+* `line.primary` (`#00000029` light, `#ffffff3d` dark): Outlined fields on hover, and unchecked choices.
+* `border.focus` (`#00000066` light, `#ffffff85` dark): The 2px outline that controls draw on keyboard focus.
+* `border.positive` (`rgb(19 169 99 / 0.16)` light, `rgb(89 229 164 / 0.32)` dark): The ring around a field that passed validation.
+* `border.warning` (`rgb(224 111 18 / 0.16)` light, `rgb(250 142 54 / 0.32)` dark): A ring that flags a field the reader should check.
+* `border.negative` (`rgb(235 52 23 / 0.16)` light, `rgb(245 92 69 / 0.32)` dark): The ring around an invalid field, checkbox, or switch.
+
+## Content
+
+Content tokens color text and icons. Pick one by how much the reader needs it.
+
+* `content.primary` (`#000` light, `#fff` dark): Titles, values, body text, and primary fills.
+* `content.secondary` (`#0000008f` light, `#ffffffa3` dark): Descriptions, captions, table cells, and placeholders.
+* `content.tertiary` (`#00000066` light, `#ffffff85` dark): Icons, chevrons, and separators beside a label.
+* `content.subtle` (`#00000033` light, `#ffffff33` dark): Tracks and marks that carry no text, such as a gauge.
+* `content.positive` (`#13a963` light, `#59e5a4` dark): Success text and icons, such as a confirmed payment.
+* `content.warning` (`#e06f12` light, `#fa8e36` dark): Caution text and icons, such as a fee warning.
+* `content.negative` (`#eb3417` light, `#f55c45` dark): Error text, field errors, and negative button fills.
+
+## Materials and Scrims
+
+Materials are translucent layers in five strengths, and scrims dim the page behind an overlay. No component uses them yet.
+
+* `material.ultrathin` (`#00000014` light, `#ffffff29` dark): The lightest translucent layer.
+* `material.thin` (`#00000033` light, `#ffffff3d` dark): A light translucent layer.
+* `material.regular` (`#00000066` light, `#ffffff7a` dark): A translucent layer of medium strength.
+* `material.thick` (`#00000099` light, `#ffffffa3` dark): A dense translucent layer.
+* `material.ultrathick` (`#000000cc` light, `#ffffffcc` dark): The densest translucent layer.
+
+* `scrim.regular` (`#00000029`): Dims the page behind an overlay, at 16% black.
+* `scrim.strong` (`#00000052`): Dims the page further, at 32% black.
+
+## Intents
+
+Components that report status take an intent, not a hue, so a status looks the same everywhere. Choose the intent by the message. An [Alert](/docs/components/alert) tints its container and colors its indicator by intent.
+
+* **Neutral (content.subtle):** Default states and features, such as a payment that is still pending.
+* **Positive (content.positive):** Success, completion, and incoming funds, such as a confirmed payment.
+* **Warning (content.warning):** A risk that the reader must know about before they confirm an action.
+* **Negative (content.negative):** Errors, failures, and destructive actions, such as a payment that failed.
+* **Tip (accent.blue.background):** Optional context, such as the token that pays the network fee for a payment.
+* **Special (accent.violet.background):** A new feature to announce, such as a vault that earns on idle USDC balances.
+
+Cyan, magenta, olive, and purple have no intent, so keep them for charts and categories.
+
+## Guidelines
+
+### Choose Tokens by Role
+
+Pick the token that names the role, not a scale step that looks right in one scheme. Never write a raw color into product styles, and propose a token in the Design System project when none fits.
+
+**Do:** Use tokens, which switch value with the scheme.
+
+```tsx
+/**
+ * Do example for "Choose Tokens by Job" on the Color page.
+ * Use tokens, which switch value with the scheme.
+ * @module
+ */
+import { style, variants } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <div {...styles.panel({ scheme: 'light' })}>
+        <span {...styles.label()}>Balance</span>
+        <span {...styles.value()}>1,250.00 USDC</span>
+      </div>
+      <div {...styles.panel({ scheme: 'dark' })}>
+        <span {...styles.label()}>Balance</span>
+        <span {...styles.value()}>1,250.00 USDC</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const panel = variants({
+    base: {
+      backgroundColor: 'background.elevated',
+      borderColor: 'line.secondary',
+      borderRadius: 'xs',
+      borderStyle: 'solid',
+      borderWidth: 'regular',
+      display: 'grid',
+      gap: '4',
+      padding: '16',
+    },
+    variants: {
+      scheme: {
+        dark: { colorScheme: 'dark !custom' },
+        light: { colorScheme: 'light !custom' },
+      },
+    },
+  })
+
+  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '12' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Fix a color that only passes in one scheme.
+
+```tsx
+/**
+ * Don't example for "Choose Tokens by Job" on the Color page.
+ * Don't fix a color that only passes in one scheme.
+ * @module
+ */
+import { style, variants } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <div {...styles.panel({ scheme: 'light' })}>
+        <span {...styles.label()}>Balance</span>
+        <span {...styles.value()}>1,250.00 USDC</span>
+      </div>
+      <div {...styles.panel({ scheme: 'dark' })}>
+        <span {...styles.label()}>Balance</span>
+        <span {...styles.value()}>1,250.00 USDC</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: '#666666 !custom', typography: 'body.b3' })
+
+  export const panel = variants({
+    base: {
+      backgroundColor: 'background.elevated',
+      borderColor: 'line.secondary',
+      borderRadius: 'xs',
+      borderStyle: 'solid',
+      borderWidth: 'regular',
+      display: 'grid',
+      gap: '4',
+      padding: '16',
+    },
+    variants: {
+      scheme: {
+        dark: { colorScheme: 'dark !custom' },
+        light: { colorScheme: 'light !custom' },
+      },
+    },
+  })
+
+  export const row = style({ display: 'flex', flexWrap: 'wrap', gap: '12' })
+
+  export const value = style({ color: '#171717 !custom', typography: 'body.b1Strong' })
+}
+```
+
+### Keep Text at Readable Contrast
+
+Set text in the primary or secondary content color, since WCAG counts it as text. Field placeholders are the exception: they take the tertiary color, as the design draws them, below 4.5:1. Otherwise keep the tertiary color for glyphs, such as chevrons and separators.
+
+**Do:** Set descriptions in `content.secondary`, which stays above 4.5:1 on both backgrounds.
+
+```tsx
+/**
+ * Do example for "Keep Text at Readable Contrast" on the Color page.
+ * Set descriptions in `content.secondary`, which stays above 4.5:1 on both backgrounds.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.title()}>Network fee</span>
+      <span {...styles.description()}>Paid in PathUSD. Settles with the payment.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const description = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const stack = style({ display: 'grid', gap: '4' })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Set text people need to read in `content.tertiary`.
+
+```tsx
+/**
+ * Don't example for "Keep Text at Readable Contrast" on the Color page.
+ * Don't set text people need to read in `content.tertiary`.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <span {...styles.title()}>Network fee</span>
+      <span {...styles.description()}>Paid in PathUSD. Settles with the payment.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const description = style({ color: 'content.tertiary', typography: 'body.b2' })
+
+  export const stack = style({ display: 'grid', gap: '4' })
+
+  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+### Reserve Accents for Meaning
+
+Blue marks information, green success, orange caution, and red errors and destructive actions. Focus and selection stay neutral.
+
+**Do:** Use red for an error or a removal.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>This access key was revoked.</Alert.Content>
+</Alert>
+```
+
+**Don't:** Use red to draw attention to a safe event.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>Your funds arrived.</Alert.Content>
+</Alert>
+```
+
+### Use One Intent per Message
+
+**Do:** Use a single warning for a single risk.
+
+```tsx
+<Alert intent="warning">
+  <Alert.Icon />
+  <Alert.Content>This address has never received a payment from you.</Alert.Content>
+</Alert>
+```
+
+**Don't:** Stack alerts of different intents for one risk.
+
+```tsx
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>New address.</Alert.Content>
+</Alert>
+<Alert intent="warning">
+  <Alert.Icon />
+  <Alert.Content>Check the address.</Alert.Content>
+</Alert>
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>Payments cannot be reversed.</Alert.Content>
+</Alert>
+```
+
+### Never Use Color Alone
+
+Pair every status color with text or an icon. In charts, name each series in a label or a legend.
+
+**Do:** Name each status in text beside its color.
+
+```tsx
+/** Do example for "Never Use Color Alone" on the Color page: name each status in text beside its color. @module */
+import { Alert, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Alert intent="positive">
+        <Alert.Icon />
+        <Alert.Content>Confirmed</Alert.Content>
+      </Alert>
+      <Alert intent="warning">
+        <Alert.Icon />
+        <Alert.Content>Pending</Alert.Content>
+      </Alert>
+      <Alert intent="negative">
+        <Alert.Icon />
+        <Alert.Content>Failed</Alert.Content>
+      </Alert>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+    width: '100% !custom',
+  })
+}
+```
+
+**Don't:** Rely on colored dots to tell Confirmed from Failed.
+
+```tsx
+/**
+ * Don't example for "Never Use Color Alone" on the Color page.
+ * Don't rely on colored dots to tell Confirmed from Failed.
+ * @module
+ */
+import { style, variants } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.dot({ intent: 'positive' })} />
+      <span {...styles.dot({ intent: 'warning' })} />
+      <span {...styles.dot({ intent: 'negative' })} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const dot = variants({
+    base: { borderRadius: 'full', cornerShape: 'round', height: '12', width: '12' },
+    variants: {
+      intent: {
+        negative: { backgroundColor: 'content.negative' },
+        positive: { backgroundColor: 'content.positive' },
+        warning: { backgroundColor: 'content.warning' },
+      },
+    },
+  })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '16' })
+}
+```
+
+## Contrast
+
+Tempo targets WCAG 2.2 AA in both schemes.
+
+* **Body Text (4.5:1):** Body text against its background.
+* **Large Text (3:1):** Text from 24px, or bold text from 18.66px.
+* **Non-Text (3:1):** Focus outlines, state borders, and icons.
+
+Each ratio lists light mode first. Several pairs fall below these targets.
+
+* **Primary on Elevated (21:1 and 18.4:1):** `content.primary` on `background.elevated`. Passes for any text, in light and dark.
+* **Secondary on Elevated (4.9:1 and 6.4:1):** `content.secondary` on `background.elevated`. Passes for body text, such as card descriptions.
+* **Secondary on Page (4.8:1 and 6.5:1):** `content.secondary` on `background.primary`. Passes for body text, such as page captions.
+* **Tertiary on Elevated (2.9:1 and 3.8:1):** `content.tertiary` glyphs, such as breadcrumb separators. Too faint for text in either scheme.
+* **Status Text on Status Fill (2.8:1+ and 4.7:1+):** `content.positive`, `warning`, and `negative` on their containers. Below 4.5:1 in light mode.
+* **Focus Outline (2.8:1 and 5.7:1):** The `border.focus` outline against the page. Below the 3:1 minimum in light mode.
+* **Invalid Border (1.3:1 and 1.6:1):** The `border.negative` ring against a surface. Below 3:1, so pair it with `Field.Error` text.
+
+Lines measure below 3:1, so they divide content but never identify a control alone. Disabled controls are exempt, but must still look disabled.
+
+## Accessibility
+
+* **Visible Focus (border.focus):** Components draw a 2px outline on keyboard focus. Don't replace it with a color change alone.
+* **Forced Colors (forced-colors):** Fields and buttons swap their resting outline for a system color outline on keyboard focus.
+
+## Related
+
+[Typography](/docs/foundations/typography)
+
+Covers text sizes that change contrast thresholds.
+
+[Accessibility](/docs/foundations/accessibility)
+
+Covers the full WCAG 2.2 AA checklist.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers choosing an intent.
+
+[Banner](/docs/components/banner)
+
+Use for status text on a status fill.
+
+[Alert](/docs/components/alert)
+
+Use for intent colors in context.
+
+[Banner](/docs/components/banner)
+
+Use for intent colors in context.