@preply/ds-docs

DS Docs (entry point)

Documentation entry point.

Using the Design System in your application or library?

Follow the instructions in @preply/ds-workspace.

Contributing

Reach out to #design-system-public if you think you can help and keep an eye on DS Confluence for more docs, guides, work in progress, decisions, the works.

CI/CD

WIP

Related scripts:

• yarn build:storybook - static build, outputs to dist/.
• yarn build:meta - copies assets, instrumentation data, and metadata collected by fe-tools

Development

You probably want to execute yarn dev and/or yarn docs in the root, as per instructions in @preply/ds-workspace.

You can also execute yarn dev in this folder, but make sure you have first executed yarn build in root, or that you have the root yarn dev script running in the background.

To execute the static build run yarn build && yarn serve.

Which documentation is included in this package?

Homepage and DS wide capabilities are documented in pages/.

Remaining docs are co-located with the source code in @preply/ds-web-lib (components) and @preply/ds-web-core (capabilities).

• *.stories.tsx - typically one single "canvas" story
• *.stories.mdx - examples, guidelines, accessibility, notes, ...

WIP Note: If you want to see live metadata on your local instance you have to follow the steps outlined in fe-tools.

Tooling

Uses storybook@latest + wepback.

Scans for pages in the monorepo, namely in:

• @preply/ds-web-lib/src/components

Details about global tools and configurations in @preply/ds-workspace.

Dependencies

This package should depend only on:

• @storybook/*** and Webpack loaders

Do NOT add dependencies on Preply component libraries, especially DS packages like ds-core, ds-web-lib, ...

webpack@4 and loaders

Storybook still ships with webpack4 but it's possible to use webpack 5.

We tried this but a series of new issues, such as this recent gh issue (Jul 2011) popped up because the plugin ecosystem is still catching up with the breaking changes.

Instead, we downgraded the css loaders gh issue to the latest versions that are compatible with Webpack4:

• css-loader@5.2.6
• less-loader@7.3.0
• postcss-loader@4.2.0
• postcss-preset-env@6.7.0
• style-loader@2.0.0

styled-components@4.1.3

Pinned to 4.1.3 to stay inline with yarn-workspace/packages/shared. Tried to update to latest: v5.3.1 (releases) but it created a fuss with hoisted deps. Not critical for this project at the moment.

Known Issues

WIP: Consolidate these notes with follow ups from previous epics

• We are using a container (addons/docs) added on each MDX page because of this issue.

• Rendering <Story> (instead of <Canvas>) in an MDX file causes Storybook to display each "story" in the Menu, which breaks the usability of the docs page (even more :-D). Some people have suggested to Add an option to hide a story from the sidebar for this same reason (as well as hiding stories that exist for snapshot purposes only). Right now I can accomplish this same thing with the block but I don't want the added link on the Sidebar.

• Even actively developing a component, the Controls widget sometimes displays props that no longer exist. It's a cache issue with typescript doc gen under the hood. You will need to restart

• First line in code samples in MDX docs are always poorly indent. Just an annoying detail.

• Code samples in Canvas page shows <StoryContextDSWeb/> because it's being injected in each stories.tsx via decorators: [story => <StoryContextDSWeb>{story()}</StoryContextDSWeb>]. It's preferrable to have this flexibility (as opposed to registering global decorators) even if the code sample is a tad polluted (another annoying detail).

• Serialization of props to url causes issue with an ugly warning react_devtools_backend.js: Omitted potentially unsafe URL args.

• FIX ME! Super annoying: Scroll to top after navigating between docs pages. Apparently this issue was fixed.