The ink ecosystem contains multiple environments utilizing the same samples. Each environment serves a different purpose but every sample adheres to ink's best practices. Samples are often served as ink guidelines or implementation references so we must keep them updated and organized.

All samples are contained in a samples.js file in each component's folder and follow this format:

{
  group: 'Component',
  name: 'Sample name must be unique',
  description: 'Relevant information', // optional
  environments: ['docs', 'expose', 'playroom'], // at least one
  code: `</>`
}

Best practices

Each sample should test and isolate an idea so we can prove weather or not it works

Follow UX Writing guidelines when adding copy. Prefer to show real language over lorem ipsum filler.
Don't duplicate existing content. Samples should work across as many environments as possible but be mindful of each environment's purpose in relation to the sample.
Keep it lean and use only the relevant props needed to achieve the sample's goal

Naming samples

All sample name should be unique, human readable and accurately describe the sample
- Example: Selectable rows
Variations and states should be appended if applicable
- Example: Selectable rows, using helpers
Add a description if clarity is needed, similar to a code comment
Avoid backticks and excessive punctuation as it can break environments like backstop

Ordering samples

Samples should be displayed starting from the most basic use cases, up to the most complex

The first sample should be the most basic. If we drop the component on a page as is with only required props, what does that look like? (default use case)
Add samples for each visual variation (variants, common use cases, patterns)
Add contextual samples for docs (recipes)
Add regression samples for common use cases with other components
Add legacy regression samples if deprecation isn't complete. We still need to ensure we've covered our ground even though it's on the way out.

Bug reports

Bugs reported to us (such as from the #ink channel) but were not regressed prior, should always have a sample added. We don't know all the use cases of how our users want to use our components but as we discover them, we should regress them to ensure that they don't reappear when we make other changes.

Environment options

At least one environment is required

environments: ["docs", "expose", "playroom"]; // compiled
environments: ["plain-text"]; // not compiled

docs

The ink documentation is our source of truth. Samples here are meant to showcase their intended usage. ALL samples here should be sharable snippets as we often send them in the #ink channel to answer questions.

Make it easy for our engineers to understand implementation details
- Elaborate with description where relevant
Add recipes as contextual samples to highlight common patterns
- Use solidBackground: true as an alternative to the transparent background in order to reflect our production environment when applicable

Don't add samples that we wouldn't encourage the use of such as legacy props or visuals. Those only need to be regressed in Exposé.

plain-text

These are snippet meant to be embedded in our docs' usage guidelines. The formatting for these don't have to adhere to any particular standard as they aren't compiled.

expose

The Exposé is used for both automated visual regression (via BackstopJS) and/or integration testing (via Cypress)

All samples displayed in docs or playroom must also appear in expose
Edge cases, uncommon use cases, legacy cases belong to expose only
Prepend Visual regression to the sample name if the sample is added specifically for BackstopJS

Check our readme for backstop for the full details. In short, samples are automatically included as a snapshot in the initial loading state via BackstopJS. Additional snapshots are added for interactive visuals such as dropdown or twiddle states (opened/closed). Snapshots can be skipped only if:

The test is flaky
- with skipFlakyBackstop: true
The initial testing state is irrelevant
- with skipInitialBackstop: true

playroom

The Playroom is our prototyping tool of choice especially useful for sharing mocks and/or debugging. Check out our Playroom 101 guide.

Contextual samples don't belong in playroom
Only the most common use cases need to be included with playroom. We don't want to pollute the quick add search! Also, all doc samples can be moved to playroom from the docs.
Don't create overly complex samples, although rare, it can freeze the editor

Other

Cypress

Check our readme for Cypress for the full details. Although not an environment option, the samples in our Exposé are also used for integration testing. We want to assert that the interactive behavior is as the user would expect.