Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Spright documentation in Storybook and README #2099

Merged
merged 6 commits into from
May 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "none",
"comment": "Update documentation about incubating components in CONTRIBUTING",
"packageName": "@ni/nimble-components",
"email": "7282195+m-akinc@users.noreply.github.com",
"dependentChangeType": "none"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "none",
"comment": "Improve Spright documentation in Storybook and README",
"packageName": "@ni/spright-components",
"email": "7282195+m-akinc@users.noreply.github.com",
"dependentChangeType": "none"
}
1 change: 0 additions & 1 deletion packages/nimble-components/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,6 @@ Before building a new component, 3 specification documents need to be created:
If a component is not ready for general use, it should be marked as "incubating" to indicate that status to clients. A component could be in this state if any of the following are true:

- It is still in development.
- It is currently experimental or application-specific and hasn't yet been generalized for broader use.
- It is missing important features like interaction design, visual design, or accessibility.

Incubating contributions may compromise on the above capabilities but they still must abide by other repository requirements. For example:
Expand Down
13 changes: 11 additions & 2 deletions packages/spright-components/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
1 change: 1 addition & 0 deletions packages/storybook/.storybook/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -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'
];
Expand Down
2 changes: 1 addition & 1 deletion packages/storybook/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
import { Meta } from '@storybook/addon-docs';

<Meta title="Patterns/all/component-apis-link" />

For more information about the structure of Nimble APIs, see [Component APIs](?path=/docs/component-apis--docs).
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import { ComponentFrameworkStatus } from './types';
import {
createUserSelectedThemeStory,
fastParameters
} from '../../utilities/storybook';
} from '../utilities/storybook';

const statusOptions = ['active', 'future'] as const;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ Components are marked as **Incubating** when they're not yet ready for general u
A component could be in this state if any of the following are true:

- It is still in development.
- It is currently experimental or application-specific and hasn't yet been generalized for broader use.
- It is missing important features like interaction design, visual design, or accessibility.

See the issue linked from each component's documentation for more information about what it's missing.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Original file line number Diff line number Diff line change
Expand Up @@ -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](https://nimble.ni.dev/) 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 <a href="./example-client-app" target="_blank">example Angular app</a> or <a href="./blazor-client-app/wwwroot" target="_blank">example Blazor app</a> using the components!

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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).
14 changes: 14 additions & 0 deletions packages/storybook/src/docs/spright.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { Story, Meta } from '@storybook/addon-docs';

<Meta title="Spright/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.
8 changes: 8 additions & 0 deletions packages/storybook/src/docs/tests-spright.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
import { Meta } from '@storybook/addon-docs';

<Meta title="Tests Spright/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).
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Original file line number Diff line number Diff line change
@@ -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';

Expand Down
2 changes: 1 addition & 1 deletion packages/storybook/src/nimble/menu/menu.mdx
Original file line number Diff line number Diff line change
@@ -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';
Expand Down
Loading