@picked/client 0.0.70-next.6 → 0.0.71-next.1

package/dist/docs/sdk/features.md

@@ -4,29 +4,40 @@ layout: docs
 
 # Feature flags
 
-Feature flags let you run A/B tests and roll changes out gradually. Manage them from the dashboard, or define them in SDK code when you need your own decision logic.
+A feature flag lets you run an A/B test and roll a change out in stages. Control a
+feature flag from the dashboard, or define it in SDK code when you need your own decision
+rules.
 
 ## Where feature flags come from
 
-Most feature flags are managed from the dashboard. The [dynamic experiences plugin](/sdk/plugins/dynamic-experiences) fetches your project configuration at runtime and registers every feature flag automatically — you do not declare them in code.
+You control most feature flags from the dashboard. The
+[dynamic experiences plugin](/sdk/plugins/dynamic-experiences) reads the options of
+your project at runtime and registers every feature flag for you. You declare no feature flag in
+code.
 
-For a dashboard-managed feature flag, the SDK generates the definition:
+For a feature flag that you control from the dashboard, the SDK makes the definition:
 
 | Field | Value |
 | --- | --- |
-| `id` | The feature flag's dashboard key |
-| `key` | `v{version}` — for example `v3` |
-| `name` | The feature flag's dashboard name |
+| `id` | The dashboard key of the feature flag |
+| `key` | `v{version}`, for example `v3` |
+| `name` | The dashboard name of the feature flag |
 | `enabled` | The dashboard **Enabled** toggle |
-| `weight` | The dashboard **Weight**, 0–100 |
+| `weight` | The dashboard **Weight**, 0 to 100 |
 | `storage` | `local`, or `session` in [preview mode](/sdk/feature-allocation#preview-mode) |
-| `decide` | Generated — allocates by comparing the visitor's stable value for this feature flag against `weight` |
+| `decide` | Made by the SDK. It compares the stable value of the visitor for this feature flag against `weight`. |
 
-The generated `decide` derives from the visitor ID, the feature flag ID, and the weight alone, so a dashboard-managed feature flag cannot base its decision on your application's data. Define the feature flag in SDK code when you need that.
+The `decide` function that the SDK makes derives from the visitor ID, the ID of the
+feature flag, and the weight. A feature flag that you control from the dashboard
+therefore cannot use the data of your application. Define the feature flag in SDK code
+when you need that.
 
-## Defining feature flags in SDK code
+## Define a feature flag in SDK code
 
-Define feature flags when creating the Picked client by passing a `features` object. Use this when a decision depends on data only your application has. Each feature flag requires a unique identifier, a versioning key, a human-readable name, and a `decide` function:
+Define your feature flags when you create the Picked client. Pass a `features` object. Use
+this when a decision needs data that only your application holds. Each feature flag needs a
+unique identifier, a version key, a name that a person can read, and a `decide`
+function:
 
 ```ts
 import { createClient } from '@picked/client'
@@ -35,20 +46,20 @@ const client = createClient({
   projectId: 'your-project-id',
   features: {
     'summer-sale': {
-      key: 'summer-sale-v1', // Version key - change to invalidate cache
-      name: 'Summer Sale Experiment', // Human-readable name for analytics
+      key: 'summer-sale-v1', // The version key. Change it to invalidate the cache.
+      name: 'Summer Sale Experiment', // A name for analytics that a person can read.
       decide: async () => {
-        // Your decision logic here
+        // Put your decision rules here.
         const isEligible = await checkUserEligibility()
-        return isEligible // Returns boolean
+        return isEligible // Returns a boolean.
       },
-      storage: 'local', // Optional: 'local' (default) or 'session'
+      storage: 'local', // Optional: 'local' is the default, or 'session'.
     },
     'homepage-variant': {
       key: 'homepage-test-v2',
       name: 'Homepage A/B Test',
       decide: async () => {
-        // Return string for multi-variant tests
+        // Return a string for a test of more than two variants.
         return Math.random() < 0.5 ? 'variant-a' : 'variant-b'
       },
     },
@@ -56,7 +67,8 @@ const client = createClient({
 })
 ```
 
-Feature flags can also be defined as factory functions for lazy initialization:
+A feature flag can also be a factory function, which starts the feature flag only when it is
+first needed:
 
 ```ts
 features: {
@@ -70,25 +82,33 @@ features: {
 
 ## How feature flags work
 
-When a feature flag is registered, the SDK follows this execution order:
+After you register a feature flag, the SDK follows this order:
 
-1. **Registration** — feature flags are registered with the client at startup. Registering does not allocate anyone.
-2. **Cache check** — the SDK looks in browser storage for a decision from a previous visit, keyed by the feature flag `id` and `key`. If one exists the feature flag starts out already resolved, which is why a returning visitor is allocated before anything reads the feature flag.
-3. **Lazy evaluation** — with no cached decision, `decide` runs the first time something reads the bucket.
-4. **Storage** — the resolved bucket is written to browser storage.
-5. **Event emission** — a `feature_decide` event fires, but only for a decision made during this page view. A decision restored in step 2 emits nothing.
+1. **Registration** — the client registers each feature flag at startup. A registration
+   allocates nobody.
+2. **Cache check** — the SDK looks in browser storage for a decision from an earlier
+   visit. The cache key holds the feature flag `id` and `key`. When an entry is there, the
+   feature flag starts in a resolved state. This is why Picked allocates a visitor who
+   returns before anything reads the feature flag.
+3. **Lazy evaluation** — with no cached decision, `decide` runs the first time that
+   something reads the bucket.
+4. **Storage** — the SDK writes the resolved bucket to browser storage.
+5. **Event emission** — the SDK sends a `feature_decide` event, but only for a
+   decision that it makes during this page view. A decision that step 2 restores
+   sends nothing.
 
-See [Allocation and exposure](/sdk/feature-allocation) for what this means when tracking exposures.
+See [Allocation and exposure](/sdk/feature-allocation) for what this means when you
+track an exposure.
 
-## URL-based overrides
+## Overrides in the URL
 
-You can override feature flag decisions via URL search parameters for testing purposes:
+You can override a feature flag decision from the URL search parameters, for a test:
 
 ```
 https://example.com?picked-feature=my-feature:true
 ```
 
-Multiple overrides can be specified:
+You can give more than one override value:
 
 ```
 https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
@@ -96,11 +116,15 @@ https://example.com?picked-feature=my-feature:true&picked-feature=homepage-varia
 
 The format is `?picked-feature=<feature-id>:<bucket-value>`.
 
-This is useful for QA testing specific bucket values without modifying code. The override is persisted in session storage and will be cleared when the browser tab is closed.
+This is useful for QA, because you can test one bucket value and change no code. The
+SDK keeps the override value in session storage. The browser clears it when you close
+the tab.
 
-## Accessing feature flags
+## Read a feature flag
 
-Once feature flags are defined, you can read their resolved bucket values in your application code. The SDK provides framework hooks and a framework-agnostic event bus.
+After you define your feature flags, your application code can read the resolved
+bucket value of each one. The SDK gives you a hook for each framework, and an event
+bus that works with any framework.
 
 :::code-group
 
@@ -108,7 +132,7 @@ Once feature flags are defined, you can read their resolved bucket values in you
 import { createClient } from '@picked/client'
 
 const client = createClient({
-  /* Create client options here */
+  /* Put your client options here. */
 })
 
 client.eventBus.watch((event) => {
@@ -122,7 +146,7 @@ client.eventBus.watch((event) => {
 <script lang="ts">
   import { getFeatureResult } from '@picked/svelte/hooks'
 
-  // A store holding { id, bucket }, or undefined until the flag resolves
+  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
   const result = getFeatureResult('my-feature')
 </script>
 
@@ -137,7 +161,7 @@ client.eventBus.watch((event) => {
 import { useFeatureResult } from '@picked/react/hooks'
 
 function MyComponent() {
-  // { id, bucket }, or undefined until the flag resolves
+  // { id, bucket }, or undefined until the feature flag resolves.
   const result = useFeatureResult('my-feature')
 
   return (
@@ -151,41 +175,46 @@ function MyComponent() {
 
 :::
 
-### Choosing an accessor
+### Choose an accessor
 
-Accessors differ in what they return, and in whether reading one resolves the feature flag. Resolving is what commits a visitor to a bucket and reports the decision — see [Allocation and exposure](/sdk/feature-allocation).
+Each accessor returns a different value. They also differ in whether a read resolves
+the feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports
+the decision. See [Allocation and exposure](/sdk/feature-allocation).
 
-| API | Returns | Resolves the feature flag? |
+| API | Returns | Does a read resolve the feature flag? |
 | --- | --- | --- |
-| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the returned function |
-| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, `undefined` until resolved | Yes, as soon as the component renders |
-| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined` — the dashboard **Enabled** toggle | No |
-| `client.features.listStore` | Every registered feature flag, each with an `isResolved` boolean | No |
-| `client.features.getById(id)` | A store holding a single feature flag | No |
+| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
+| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
+| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** toggle | No |
+| `client.features.listStore` | Every registered feature flag, each with an `isResolved` feature flag | No |
+| `client.features.getById(id)` | A store that holds one feature flag | No |
 
 :::warning
-`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component renders, committing the visitor to a bucket at that moment.
+`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
+renders. They commit the visitor to a bucket at that moment.
 
-If the decision should wait for data you do not have yet — a cart, a quote, a signed-in profile — use `useFeature` or `getFeature` and call the function they return once that data arrives.
+Some decisions must wait for data that you do not have yet, such as a cart, a quote,
+or a profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call
+the function that they return after the data arrives.
 :::
 
-## Using feature flags in experience conditions
+## Use a feature flag in an experience condition
 
-Feature flags can be used with experience conditions via JSON logic:
+You can use a feature flag in an experience condition through JSON logic:
 
 ```ts
 const myExperience = createExperience({
-  // ... other config
+  // The other options go here.
   condition: {
     and: [
       {
         '==': [
           {
             invoke: {
-              var: 'features.summer-sale', // Reference the flag by ID
+              var: 'features.summer-sale', // Point at the feature flag by its ID.
             },
           },
-          true, // Check if bucket equals true
+          true, // Check that the bucket equals true.
         ],
       },
     ],
@@ -193,13 +222,15 @@ const myExperience = createExperience({
 })
 ```
 
-The ID in `features.<id>` is the feature flag's **Key** from the dashboard — the same value shown on the feature flag detail page.
+The ID in `features.<id>` is the **Key** of the feature flag from the dashboard. It is the
+same value that the detail page of the feature flag shows.
 
-Evaluating a condition reads the bucket, so a feature flag referenced by an experience condition is allocated at the moment that condition runs.
+An evaluation of a condition reads the bucket. Picked therefore allocates a visitor
+to a feature flag when the condition that points at it runs.
 
-## Listening to feature flag decisions
+## Watch for feature flag decisions
 
-Subscribe to the `feature_decide` event to track when feature flags are resolved:
+Subscribe to the `feature_decide` event to track when a feature flag resolves:
 
 ```ts
 client.eventBus.watch((event) => {
@@ -207,9 +238,9 @@ client.eventBus.watch((event) => {
 
   const { feature } = event
   console.log(`Flag "${feature.id}" resolved to bucket:`, feature.bucket)
-  // Example output: Flag "summer-sale" resolved to bucket: true
+  // Example output: the feature flag resolved to the bucket true.
 
-  // Send to analytics
+  // Send the decision to your analytics.
   analytics.track('Feature Decision', {
     featureId: feature.id,
     bucket: feature.bucket,
@@ -217,50 +248,73 @@ client.eventBus.watch((event) => {
 })
 ```
 
-## Versioning and cache invalidation
+## Versions and cache invalidation
 
-Feature flag decisions are cached in browser storage (localStorage, or sessionStorage in preview) under a key derived from the feature flag ID and version, so a visitor keeps the same decision across page loads.
+The SDK caches a feature flag decision in browser storage. It uses `localStorage`, or
+`sessionStorage` in a preview. The cache key derives from the feature flag ID and the version,
+so a visitor keeps the same decision across page loads.
 
 :::warning
-Bucket values that are strings, such as `'variant-a'`, are not yet restored correctly from storage — the visitor is treated as unallocated on their next page load. Boolean bucket values, which includes every feature flag managed from the dashboard, are unaffected. Tracked in PICK-1574.
+The SDK does not yet restore a string bucket value, such as `'variant-a'`, correctly
+from storage. It treats the visitor as unallocated on the next page load. A boolean
+bucket value is correct, and that includes every feature flag that you control from the
+dashboard. See PICK-1574.
 :::
 
-### How versioning works
+### How versions work
 
-When you create a feature flag in the dashboard, it starts at version 1. The SDK uses the version to build the cache key — for example, a feature flag at version 3 caches under `v3`.
+A feature flag that you create in the dashboard starts at version 1. The SDK uses the
+version to build the cache key. A feature flag at version 3 caches under `v3`.
 
-The version affects **caching only**. It is not part of the allocation calculation, which for dashboard-managed feature flags derives from the visitor ID, the feature flag ID, and the feature flag's weight.
+The version affects **the cache only**. It is not part of the allocation. For a feature flag
+that you control from the dashboard, the allocation derives from the visitor ID and
+the weight of the feature flag.
 
-### What happens when the version is incremented
+### What happens when you increment the version
 
-When you increment a feature flag's version in the dashboard:
+When you increment the version of a feature flag in the dashboard:
 
-1. **Cache keys change.** The old cache entry (e.g., `v3`) no longer matches the new key (`v4`), so the SDK treats the feature flag as undecided.
-2. **The `decide` function runs again.** On the next page load, the SDK calls `decide()` fresh and caches the new result.
-3. **Visitors are re-evaluated, not reshuffled.** For dashboard-managed feature flags allocation is deterministic, so re-evaluating the same visitor against an unchanged weight produces the same bucket.
+1. **The cache key changes.** The old entry, `v3`, no longer matches the new key,
+   `v4`. The SDK therefore treats the feature flag as undecided.
+2. **The `decide` function runs again.** On the next page load, the SDK calls
+   `decide()` again and caches the new result.
+3. **Picked evaluates each visitor again and moves nobody.** For a feature flag that you
+   control from the dashboard the allocation is deterministic. The same visitor
+   against an unchanged weight gives the same bucket.
 
 :::note
-Incrementing the version clears cached decisions and runs allocation again. It does not randomise visitors — with an unchanged weight, everyone lands where they were. Increment it after changing a weight, so visitors who already hold a cached decision are re-evaluated against the new one.
+The new version clears the cached decisions and runs the allocation again. It moves
+no visitor between groups. With an unchanged weight, everybody lands where they were.
+Increment the version after you change a weight, so that Picked evaluates a visitor
+with a cached decision against the new weight.
 :::
 
-### SDK `key` vs dashboard version
+### The SDK `key` and the dashboard version
 
-If you define feature flags statically in the SDK (not loaded from the dashboard), use the `key` field for manual versioning:
+For a feature flag that you define in SDK code, use the `key` field to set the version
+yourself. This applies when you do not read the feature flag from the dashboard:
 
 ```ts
 features: {
   'summer-sale': {
-    key: 'summer-sale-v2', // Change to invalidate cache
-    // ...
+    key: 'summer-sale-v2', // Change this to invalidate the cache.
+    // The other options go here.
   },
 }
 ```
 
-For feature flags managed through the dashboard, versioning is handled automatically — the dashboard appends the version number to the cache key used by the SDK.
+For a feature flag that you control from the dashboard, Picked sets the version for you. The
+dashboard adds the version number to the end of the cache key that the SDK uses.
 
 ## Best practices
 
-- **Use `session` storage for temporary tests**: Set `storage: 'session'` for short-lived experiments that shouldn't persist across browser sessions
-- **Keep `decide` functions fast**: Anything awaiting the feature flag — an experience condition, a component reading the result — waits for `decide` to finish, so avoid slow network calls inside it
-- **Allocate when the decision matters**: Defer reading a feature flag until the data it depends on has arrived, rather than reading every feature flag at startup. See [Allocation and exposure](/sdk/feature-allocation)
-- **Return consistent types**: Don't mix boolean and string returns for the same feature flag - pick one type and stick with it
+- **Use `session` storage for a short test**: set `storage: 'session'` for an
+  experiment that must not stay across browser sessions.
+- **Keep each `decide` function fast**: everything that waits for the feature flag waits for
+  `decide` to finish. This includes an experience condition and a component that
+  reads the result. Do not make a slow network call inside it.
+- **Allocate when the decision matters**: read a feature flag only after the data that it
+  needs arrives. Do not read every feature flag at startup. See
+  [Allocation and exposure](/sdk/feature-allocation).
+- **Return one type**: do not return a boolean from a feature flag one time and a string the
+  next. Choose one type and keep it.

package/dist/docs/sdk/fields.md

@@ -4,16 +4,19 @@ layout: docs
 
 # Fields
 
-Define fields in code with `createField()`, validate input with JSON Logic, and read submitted values through step context.
+Define your fields in code with `createField()`. Check the input with JSON Logic.
+Read the values that a user sends through the step context.
 
-## Defining fields
+## Define a field
 
-Define fields using `createField()` from the `@picked/client/plugins/create-experience` package. Each field requires a unique identifier, name, type, label, and cardinality:
+Define a field with `createField()` from the
+`@picked/client/plugins/create-experience` package. Each field needs a unique
+identifier, a name, a type, a label, and a count of the values that it takes:
 
 ```ts
 import { createField } from '@picked/client/plugins/create-experience'
 
-// Required text input
+// A text input that the user must fill in.
 export const emailField = createField({
   id: 'email-address',
   name: 'email-address',
@@ -24,7 +27,7 @@ export const emailField = createField({
   placeholder: 'you@example.com',
 })
 
-// Multi-select dropdown with static options
+// A dropdown that takes more than one choice, with fixed options.
 export const communicationMethods = createField({
   id: 'communication-methods',
   name: 'communication-methods',
@@ -54,21 +57,28 @@ export const communicationMethods = createField({
 
 ## How fields work
 
-When a field is registered and used in an experience:
-
-1. **Registration**: Fields are registered to the experience during step creation via `.addField()`
-2. **Condition Evaluation**: If the field has a `condition`, it's evaluated against the current context to determine visibility
-3. **Rendering**: Visible fields are rendered in the experience UI with their label, placeholder, and options
-4. **User Input**: User enters or selects a value, triggering client-side validation if specified
-5. **Storage**: Valid responses are stored in the experience state under `responses[field.name]`
-6. **Reference**: Field values can be referenced in subsequent field conditions, step conditions, or experience logic via `{ var: 'responses.field-name' }`
+After you register a field and an experience uses it:
+
+1. **Registration**: you register a field on the experience while you create the
+   step, with `.addField()`.
+2. **Condition evaluation**: when the field has a `condition`, the SDK evaluates it
+   against the current context. The result decides whether the field is visible.
+3. **Rendering**: the SDK renders each visible field in the experience UI, with its
+   label, its placeholder, and its options.
+4. **User input**: the user enters or chooses a value. Validation then runs in the
+   browser, when you set a rule.
+5. **Storage**: the SDK stores a valid response in the experience state, under
+   `responses[field.name]`.
+6. **Reference**: a later condition can point at the value with
+   `{ var: 'responses.field-name' }`. This works in a field condition, in a step
+   condition, and in the logic of an experience.
 
 ## Field types
 
-Fields support four primitive types, `text`, `number`, `boolean` and `object`:
+A field has one of four basic types: `text`, `number`, `boolean`, or `object`.
 
 ```ts
-// Single text input
+// One text input.
 const nameField = createField({
   type: 'text',
   multiple: false,
@@ -76,7 +86,7 @@ const nameField = createField({
 })
 ```
 
-Provide an `options` array to allow multiple select:
+Give an `options` array to let the user choose more than one value:
 
 ```ts
 const nameField = createField({
@@ -104,7 +114,7 @@ const nameField = createField({
 
 ## Conditions
 
-Fields and field options are compatible with condition logic:
+A field and a field option both work with condition logic:
 
 ```ts
 const conditionalField = createField({
@@ -131,7 +141,8 @@ const conditionalField = createField({
 
 ## Field validation
 
-Validate user input using JSON Logic rules. The `$input` variable contains the current field value:
+Check the input of a user with a JSON Logic rule. The `$input` variable holds the
+current value of the field:
 
 ```ts
 const quantityField = createField({
@@ -147,7 +158,7 @@ const quantityField = createField({
         {
           and: [
             {
-              // Input value is above 0
+              // The input value is above 0.
               '>': [
                 {
                   var: '$input',
@@ -156,7 +167,7 @@ const quantityField = createField({
               ],
             },
             {
-              // Input value is equal or below 999
+              // The input value is 999 or below.
               '<=': [
                 {
                   var: '$input',
@@ -176,12 +187,13 @@ const quantityField = createField({
 ```
 
 :::tip
-The `catch`/`throw` pattern in JSON Logic validates that the condition evaluates to `true`. If it doesn't, the `throw` message is displayed to the user.
+The `catch` and `throw` pattern in JSON Logic checks that the condition gives `true`.
+When it does not, the SDK shows the `throw` message to the user.
 :::
 
 ## Field policies
 
-Control how field data is tracked and stored using privacy policies:
+Use a privacy policy to control how Picked tracks and stores the data of a field:
 
 ```ts
 const sensitiveField = createField({
@@ -192,22 +204,25 @@ const sensitiveField = createField({
   multiple: false,
   required: true,
   policies: {
-    doNotTrackValue: true, // Don't send value to analytics
-    doNotStoreValue: true, // Don't persist value to browser storage
+    doNotTrackValue: true, // Do not send the value to analytics.
+    doNotStoreValue: true, // Do not keep the value in browser storage.
   },
 })
 ```
 
 **Privacy policies**:
 
-- `doNotTrackValue`: Excludes field value from analytics events (only field ID is tracked)
-- `doNotStoreValue`: Prevents field value from being persisted to browser storage
+- `doNotTrackValue`: keeps the value of the field out of your analytics events. The
+  events carry the field ID only.
+- `doNotStoreValue`: stops the SDK, so that it does not put the value in browser
+  storage.
 
-Use these policies for sensitive data like SSNs, credit cards, or passwords that should only exist client-side.
+Use these policies for sensitive data such as a tax number, a credit card number, or
+a password. That data must stay in the browser.
 
 ## Field metadata
 
-Enhance user experience with additional descriptive text:
+Add more text to help the user:
 
 ```ts
 const passwordField = createField({
@@ -225,18 +240,19 @@ const passwordField = createField({
 
 **Metadata fields**:
 
-- `placeholder`: Hint text displayed in empty input fields
-- `description`: Brief explanation shown below the label
-- `helpText`: Additional guidance or requirements displayed near the field
+- `placeholder`: the hint text that an empty input shows.
+- `description`: a short explanation below the label.
+- `helpText`: more guidance, or the requirements, next to the field.
 
-## Accessing field values
+## Read a field value
 
-Field responses are stored in the experience state and can be accessed via the `responses` object:
+The SDK stores each field response in the experience state. Read a response through
+the `responses` object:
 
 :::code-group
 
 ```ts [In Conditions]
-// Reference in subsequent field conditions
+// Point at the value from a later field condition.
 const sensitiveField = createField({
   condition: {
     '==': [
@@ -253,11 +269,19 @@ const sensitiveField = createField({
 
 ## Best practices
 
-- **Use semantic IDs and names**: Name fields descriptively (e.g., `email-address` not `field1`) for easier debugging and analytics
-- **Match type to data**: Use `number` for numeric values, not `text`, to enable proper validation and comparison
-- **Set appropriate `required` flags**: Only mark fields as required when truly necessary to reduce form abandonment
-- **Keep validation messages clear**: Error messages should tell users exactly how to fix the input
-- **Use conditional fields for progressive disclosure**: Show fields only when relevant based on prior responses
-- **Apply privacy policies to sensitive data**: Use `doNotTrackValue` and `doNotStoreValue` for PII, passwords, or financial data
-- **Provide helpful metadata**: Add `placeholder` and `description` to guide users, especially for complex or formatted inputs
-- **Keep option lists scannable**: For more than 5 options, consider providing search/filter functionality or breaking into multiple steps
+- **Give each field a name that says what it holds**: use `email-address` and not
+  `field1`. It is then easier to debug the flow and to read your analytics.
+- **Match the type to the data**: use `number` for a numeric value, and not `text`.
+  The SDK can then check and compare the value correctly.
+- **Mark a field as required only when it is**: fewer required fields means fewer
+  users who leave the form.
+- **Keep each validation message clear**: an error message must tell the user exactly
+  how to correct the input.
+- **Show a field only when it is relevant**: use a condition on the field, and decide
+  it from the earlier responses.
+- **Apply a privacy policy to sensitive data**: use `doNotTrackValue` and
+  `doNotStoreValue` for personal information, a password, or financial data.
+- **Give helpful metadata**: add a `placeholder` and a `description` to help the
+  user, above all for an input with a format.
+- **Keep an option list easy to read**: for more than 5 options, add a search or
+  break the field into more than one step.