From 2ff96c5cc68eb8a4bd53df8a5defd40e5b93ba46 Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 10 May 2024 16:43:01 -0500 Subject: [PATCH] Improve Spright documentation in Storybook and README --- packages/spright-components/README.md | 13 +++++++++++-- packages/storybook/.storybook/main.js | 1 + packages/storybook/README.md | 2 +- .../patterns => }/docs/component-apis-link.mdx | 4 ++++ .../src/{nimble/tests => docs}/component-apis.mdx | 0 .../{nimble/tests => docs}/component-status.mdx | 0 .../tests => docs}/component-status.stories.ts | 2 +- .../src/{nimble/tests => docs}/incubating.mdx | 0 .../src/{nimble/tests => docs}/internal.mdx | 2 +- .../src/{nimble/tests => docs}/nimble-intro.mdx | 8 +++++--- .../{nimble/tests => docs}/nimble-logo-icon.svg | 0 .../src/{nimble/tests => docs}/patterns.mdx | 2 +- packages/storybook/src/docs/spright.mdx | 14 ++++++++++++++ .../{nimble/tests => docs}/storybook-overview.png | Bin packages/storybook/src/docs/tests-spright.mdx | 8 ++++++++ .../src/{nimble/tests => docs}/tests.mdx | 2 +- .../storybook/src/{nimble/tests => docs}/types.ts | 0 .../src/nimble/menu-button/menu-button.mdx | 2 +- packages/storybook/src/nimble/menu/menu.mdx | 2 +- 19 files changed, 50 insertions(+), 12 deletions(-) rename packages/storybook/src/{nimble/patterns => }/docs/component-apis-link.mdx (53%) rename packages/storybook/src/{nimble/tests => docs}/component-apis.mdx (100%) rename packages/storybook/src/{nimble/tests => docs}/component-status.mdx (100%) rename packages/storybook/src/{nimble/tests => docs}/component-status.stories.ts (99%) rename packages/storybook/src/{nimble/tests => docs}/incubating.mdx (100%) rename packages/storybook/src/{nimble/tests => docs}/internal.mdx (68%) rename packages/storybook/src/{nimble/tests => docs}/nimble-intro.mdx (77%) rename packages/storybook/src/{nimble/tests => docs}/nimble-logo-icon.svg (100%) rename packages/storybook/src/{nimble/tests => docs}/patterns.mdx (70%) create mode 100644 packages/storybook/src/docs/spright.mdx rename packages/storybook/src/{nimble/tests => docs}/storybook-overview.png (100%) create mode 100644 packages/storybook/src/docs/tests-spright.mdx rename packages/storybook/src/{nimble/tests => docs}/tests.mdx (69%) rename packages/storybook/src/{nimble/tests => docs}/types.ts (100%) diff --git a/packages/spright-components/README.md b/packages/spright-components/README.md index af9f146476..52a4b92d4d 100644 --- a/packages/spright-components/README.md +++ b/packages/spright-components/README.md @@ -6,6 +6,15 @@ [![NPM Version](https://img.shields.io/npm/v/@ni/spright-components.svg)](https://www.npmjs.com/package/@ni/spright-components) -NI-styled web components following [Nimble Design System](https://nimble.ni.dev) patterns but not part of the core design system. +NI-styled web components following [Nimble Design System](https://nimble.ni.dev) patterns and built on the same technologies (FAST, native web components, etc.), but not part of the core design system. -The `spright-components` package is intended for components that do not belong in [`nimble-components`](/packages/nimble-components) due to being: ["molecules"](https://atomicdesign.bradfrost.com/chapter-2/), product-specific, data-connected, or not "general utility". The primary component implementations are built on Nimble technologies (FAST, native web components, etc). +The `spright-components` package is intended for components that do not belong in [`nimble-components`](/packages/nimble-components) due to being: ["molecules"](https://atomicdesign.bradfrost.com/chapter-2/), product-specific, data-connected, or not "general utility". Some examples: + +- Molecule: a group of card buttons with a specific layout +- Product-specific: a configuration pane that uses product-specific terminology or connects to a product-specific data model +- Data-connected: a table that populates itself by making HTTP requests to a specific service +- Experimental components that are trying out new UX patterns to see if they should someday be promoted to Nimble. + +## Why Spright? + +"Spright" is an archaic variant of "sprite" that is the root of "sprightly"; think of it as a rapidly moving peer of Nimble. diff --git a/packages/storybook/.storybook/main.js b/packages/storybook/.storybook/main.js index 749020fc98..c0d0cf042b 100644 --- a/packages/storybook/.storybook/main.js +++ b/packages/storybook/.storybook/main.js @@ -6,6 +6,7 @@ import TerserPlugin from 'terser-webpack-plugin'; // All files participating in storybook should be in src // so that TypeScript and linters can track them correctly export const stories = [ + '../src/docs', '../src/nimble', '../src/spright' ]; diff --git a/packages/storybook/README.md b/packages/storybook/README.md index cca6d9f04f..a8f5b6bebd 100644 --- a/packages/storybook/README.md +++ b/packages/storybook/README.md @@ -4,5 +4,5 @@ Private package containing the Storybook for the Nimble repo. ## Contributing -See `Getting Started` in [`CONTRIBUTING.md`](/CONTRIBUTING.md#getting-started) to get started with building +See `Getting Started` in [`CONTRIBUTING.md`](/packages/storybook/CONTRIBUTING.md) to get started with building and running storybook. \ No newline at end of file diff --git a/packages/storybook/src/nimble/patterns/docs/component-apis-link.mdx b/packages/storybook/src/docs/component-apis-link.mdx similarity index 53% rename from packages/storybook/src/nimble/patterns/docs/component-apis-link.mdx rename to packages/storybook/src/docs/component-apis-link.mdx index 3ee8ee4319..4b1169b251 100644 --- a/packages/storybook/src/nimble/patterns/docs/component-apis-link.mdx +++ b/packages/storybook/src/docs/component-apis-link.mdx @@ -1 +1,5 @@ +import { Meta } from '@storybook/addon-docs'; + + + For more information about the structure of Nimble APIs, see [Component APIs](?path=/docs/component-apis--docs). diff --git a/packages/storybook/src/nimble/tests/component-apis.mdx b/packages/storybook/src/docs/component-apis.mdx similarity index 100% rename from packages/storybook/src/nimble/tests/component-apis.mdx rename to packages/storybook/src/docs/component-apis.mdx diff --git a/packages/storybook/src/nimble/tests/component-status.mdx b/packages/storybook/src/docs/component-status.mdx similarity index 100% rename from packages/storybook/src/nimble/tests/component-status.mdx rename to packages/storybook/src/docs/component-status.mdx diff --git a/packages/storybook/src/nimble/tests/component-status.stories.ts b/packages/storybook/src/docs/component-status.stories.ts similarity index 99% rename from packages/storybook/src/nimble/tests/component-status.stories.ts rename to packages/storybook/src/docs/component-status.stories.ts index 45638adcf0..0a11c56919 100644 --- a/packages/storybook/src/nimble/tests/component-status.stories.ts +++ b/packages/storybook/src/docs/component-status.stories.ts @@ -11,7 +11,7 @@ import { ComponentFrameworkStatus } from './types'; import { createUserSelectedThemeStory, fastParameters -} from '../../utilities/storybook'; +} from '../utilities/storybook'; const statusOptions = ['active', 'future'] as const; diff --git a/packages/storybook/src/nimble/tests/incubating.mdx b/packages/storybook/src/docs/incubating.mdx similarity index 100% rename from packages/storybook/src/nimble/tests/incubating.mdx rename to packages/storybook/src/docs/incubating.mdx diff --git a/packages/storybook/src/nimble/tests/internal.mdx b/packages/storybook/src/docs/internal.mdx similarity index 68% rename from packages/storybook/src/nimble/tests/internal.mdx rename to packages/storybook/src/docs/internal.mdx index bfd3f2ae57..0e18d341f5 100644 --- a/packages/storybook/src/nimble/tests/internal.mdx +++ b/packages/storybook/src/docs/internal.mdx @@ -5,4 +5,4 @@ import { Meta } from '@storybook/addon-docs'; # Internal 🙈 Nothing to see here! The **Internal** section contains stories that are used by other documentation. -It's hidden from public documentation on nimble.ni.dev. +It's hidden from public documentation on [nimble.ni.dev](https://nimble.ni.dev/storybook). diff --git a/packages/storybook/src/nimble/tests/nimble-intro.mdx b/packages/storybook/src/docs/nimble-intro.mdx similarity index 77% rename from packages/storybook/src/nimble/tests/nimble-intro.mdx rename to packages/storybook/src/docs/nimble-intro.mdx index c26d040923..41ccaf6610 100644 --- a/packages/storybook/src/nimble/tests/nimble-intro.mdx +++ b/packages/storybook/src/docs/nimble-intro.mdx @@ -10,13 +10,15 @@ import nimbleLogo from './nimble-logo-icon.svg'; ## Overview -The [Nimble Design System](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/) is an easy to use collection of well-designed, +The Nimble Design System is an easy to use collection of well-designed, styled components that can be used in any NI web application. +Outside the core design system, the [Spright component collection](https://github.com/ni/nimble/tree/main/packages/spright-components/README.md) is home to more complex, experimental, or application-specific components. + Refer to the [Nimble GitHub repository](https://github.com/ni/nimble) for documentation on using or -contributing to the component library. To add or update component design documentation, -refer to the [documentation guide](https://github.com/ni/nimble/tree/main/packages/nimble-components/docs/creating-storybook-component-documentation.md). +contributing to the component libraries. To add or update component design documentation, +refer to the [documentation guide](https://github.com/ni/nimble/tree/main/packages/storybook/CONTRIBUTING.md). See the example Angular app or example Blazor app using the components! diff --git a/packages/storybook/src/nimble/tests/nimble-logo-icon.svg b/packages/storybook/src/docs/nimble-logo-icon.svg similarity index 100% rename from packages/storybook/src/nimble/tests/nimble-logo-icon.svg rename to packages/storybook/src/docs/nimble-logo-icon.svg diff --git a/packages/storybook/src/nimble/tests/patterns.mdx b/packages/storybook/src/docs/patterns.mdx similarity index 70% rename from packages/storybook/src/nimble/tests/patterns.mdx rename to packages/storybook/src/docs/patterns.mdx index 55fa0d3bfc..563ea9f0a6 100644 --- a/packages/storybook/src/nimble/tests/patterns.mdx +++ b/packages/storybook/src/docs/patterns.mdx @@ -5,4 +5,4 @@ import { Meta } from '@storybook/addon-docs'; # Patterns 🙈 Nothing to see here! The **Patterns** section contains shared documentation snippets for shared implementation patterns. -It's hidden from public documentation on nimble.ni.dev. +It's hidden from public documentation on [nimble.ni.dev](https://nimble.ni.dev/storybook). diff --git a/packages/storybook/src/docs/spright.mdx b/packages/storybook/src/docs/spright.mdx new file mode 100644 index 0000000000..5ea7ae9fdb --- /dev/null +++ b/packages/storybook/src/docs/spright.mdx @@ -0,0 +1,14 @@ +import { Story, Meta } from '@storybook/addon-docs'; + + + +# Spright components + +These components adhere to Nimble's styling and API conventions, but are not part of the core design system due to having one or more of the following characteristics: + +- more complex ["molecules"](https://atomicdesign.bradfrost.com/chapter-2/) composed of Nimble "atom" components +- inherently product-specific in a way that makes reuse by other applications unlikely +- data-connected +- otherwise lacking general utility + +Spright components are production-quality, but may not have the same level of documentation or cross-framework support as Nimble components. \ No newline at end of file diff --git a/packages/storybook/src/nimble/tests/storybook-overview.png b/packages/storybook/src/docs/storybook-overview.png similarity index 100% rename from packages/storybook/src/nimble/tests/storybook-overview.png rename to packages/storybook/src/docs/storybook-overview.png diff --git a/packages/storybook/src/docs/tests-spright.mdx b/packages/storybook/src/docs/tests-spright.mdx new file mode 100644 index 0000000000..99ea73b5ff --- /dev/null +++ b/packages/storybook/src/docs/tests-spright.mdx @@ -0,0 +1,8 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Tests Spright + +🙈 Nothing to see here! The **Tests Spright** section contains stories that are used by Nimble for visual comparison testing. +It's hidden from public documentation on [nimble.ni.dev](https://nimble.ni.dev/storybook). diff --git a/packages/storybook/src/nimble/tests/tests.mdx b/packages/storybook/src/docs/tests.mdx similarity index 69% rename from packages/storybook/src/nimble/tests/tests.mdx rename to packages/storybook/src/docs/tests.mdx index 86d5c4f0c6..1842234025 100644 --- a/packages/storybook/src/nimble/tests/tests.mdx +++ b/packages/storybook/src/docs/tests.mdx @@ -5,4 +5,4 @@ import { Meta } from '@storybook/addon-docs'; # Tests 🙈 Nothing to see here! The **Tests** section contains stories that are used by Nimble for visual comparison testing. -It's hidden from public documentation on nimble.ni.dev. +It's hidden from public documentation on [nimble.ni.dev](https://nimble.ni.dev/storybook). diff --git a/packages/storybook/src/nimble/tests/types.ts b/packages/storybook/src/docs/types.ts similarity index 100% rename from packages/storybook/src/nimble/tests/types.ts rename to packages/storybook/src/docs/types.ts diff --git a/packages/storybook/src/nimble/menu-button/menu-button.mdx b/packages/storybook/src/nimble/menu-button/menu-button.mdx index 0e350cc78d..08cf0a8795 100644 --- a/packages/storybook/src/nimble/menu-button/menu-button.mdx +++ b/packages/storybook/src/nimble/menu-button/menu-button.mdx @@ -1,7 +1,7 @@ import { Controls, Canvas, Meta, Title } from '@storybook/blocks'; import ContentHiddenDocs from '../patterns/button/content-hidden-docs.mdx'; import StylingDocs from '../patterns/button/styling-docs.mdx'; -import ComponentApisLink from '../patterns/docs/component-apis-link.mdx'; +import ComponentApisLink from '../../docs/component-apis-link.mdx'; import { menuButtonTag } from '@ni/nimble-components/dist/esm/menu-button'; import * as menuButtonStories from './menu-button.stories'; diff --git a/packages/storybook/src/nimble/menu/menu.mdx b/packages/storybook/src/nimble/menu/menu.mdx index de16d3422f..b9e3fca23f 100644 --- a/packages/storybook/src/nimble/menu/menu.mdx +++ b/packages/storybook/src/nimble/menu/menu.mdx @@ -1,6 +1,6 @@ import { Controls, Canvas, Meta, Title } from '@storybook/blocks'; import TargetDocs from '../patterns/anchor/target-docs.mdx'; -import ComponentApisLink from '../patterns/docs/component-apis-link.mdx'; +import ComponentApisLink from '../../docs/component-apis-link.mdx'; import * as menuStories from './menu.stories'; import { menuTag } from '@ni/nimble-components/dist/esm/menu'; import { menuItemTag } from '@ni/nimble-components/dist/esm/menu-item';